Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

This is a breaking change, right? Can we perhaps add a hidden positional argument that gives a better error message? E.g. something like 'use the --node argument' instead of just failing with a generic "unexpected argument" error?

There are also some docs that still use the old syntax after this PR, e.g. quickstart.md or the guide. These need to be fixed before merging.

Addressed this in 17bb016a:

• added a hidden legacy positional node argument so dora logs <dataflow> <node> reaches a targeted runtime hint instead of a clap parse error
• kept the --node path as the documented node filter
• updated the stale quickstart and README.zh-CN references

Validation:

• cargo fmt -p dora-cli -- --check
• cargo test -p dora-cli command::tests::parse_logs -- --nocapture (6 passed, 0 failed)
• cargo run -p dora-cli --bin dora -- logs my-dataflow sensor -> reports: "hint: use dora logs my-dataflow --node sensor instead"
• git diff --check
• git diff -- binaries/cli/src/command/logs.rs binaries/cli/src/command/mod.rs README.zh-CN.md docs/quickstart.md | gitleaks detect --pipe --redact --no-banner -> no leaks found

Did a pre-landing review pass. The PR is solid: the hidden-legacy-positional + targeted-hint approach from phil-opp's review was the right call, the parser tests cover the main shapes, and the doc updates are thorough (README, README.zh-CN, all 5 docs/*.md, plus the daemon-side error message in pending.rs). All 7 new parser tests pass locally.

Three minor UX nits worth flagging. None of these are merge blockers, just polish opportunities for either this PR or a follow-up.

1. Misleading hint when both legacy positional and --node are set

binaries/cli/src/command/logs.rs:158-167 — reject_legacy_node_arg constructs the hint from args.legacy_node. When the user types dora logs DF NODE --node OTHER, both fields populate and the bail message ends up saying "use dora logs DF --node NODE" — pointing them at the legacy value they're already trying to override with their explicit --node OTHER.

Suggested message branch:

match (&args.legacy_node, &args.node) {
    (Some(legacy), Some(explicit)) => bail!(
        "positional node `{legacy}` is not allowed alongside `--node {explicit}`; \
         drop the positional argument"
    ),
    (Some(legacy), None) => bail!(
        "positional node argument `{legacy}` is no longer supported\n\n  \
         hint: use `dora logs {dataflow} --node {legacy}` instead"
    ),
    _ => Ok(()),
}

2. legacy_positional_node heuristic fires on any lookup failure

binaries/cli/src/command/logs.rs:169-173 — the hint "if X is a node name, use --node X" is appended whenever a single-positional dora logs X resolution fails, regardless of why. That's the intended help when X was actually a misplaced node name, but it's confusing for legitimate failures (coordinator unreachable, transient 500, dataflow in Failed state) where X IS a real dataflow.

Worth narrowing to only the "not found" error class once you can tell them apart from resolve_dataflow_identifier_interactive's error shape. INVESTIGATE — depends on whether that resolver distinguishes lookup-miss from transport errors.

3. legacy_node lacks conflicts_with declarations + test gap

binaries/cli/src/command/logs.rs:28-31 — legacy_node has no conflicts_with for node or all_nodes. The combinations dora logs DF NODE --all-nodes and dora logs DF NODE --node OTHER parse successfully and then reject_legacy_node_arg fires with a hint that, in both cases, contradicts the user's other flag. Adding conflicts_with = ["node", "all_nodes"] on legacy_node would let clap reject the worst combinations at parse time with a cleaner error path; alternatively keep the runtime guard but make the hint conditional on the other flags (as in #1).

A parse_ok test for dora logs my-dataflow sensor --node other (followed by an integration-style assertion on execute() failure) would catch any regression in the hint message.

Reproduced locally with cargo test -p dora-cli --lib -- parse_logs reject_logs (7/7 pass on the existing tests). Happy to follow up with a separate cleanup PR if maintainers prefer to land this as-is and iterate.

Addressed the conflict-handling nits in b15efe2.\n\nChanges:\n- Added clap conflicts for the hidden legacy positional node argument against both --node and --all-nodes, so dora logs DF NODE --node OTHER and dora logs DF NODE --all-nodes now fail at parse time with a direct conflict error.\n- Added parser regression coverage for both combinations.\n- Softened the fallback lookup hint to say "if you intended ... as a node name" so it is less misleading when the underlying dataflow lookup failed for another reason.\n\nValidation:\n- cargo fmt -p dora-cli -- --check\n- cargo test -p dora-cli command::tests:: -- --nocapture -> 76 passed, 0 failed\n- cargo run -p dora-cli --bin dora -- logs my-dataflow sensor --node other -> rejects [NAME] with --node\n- cargo run -p dora-cli --bin dora -- logs my-dataflow sensor --all-nodes -> rejects [NAME] with --all-nodes\n- git diff --check\n- changed diff gitleaks scan -> no leaks found